home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / edit / me_cd25.zip / DOC.ZIP / MM2.DOC < prev    next >
Text File  |  1992-11-09  |  30KB  |  961 lines
  1. ========================================================================
  2. ==        The Mutt2 Machine          Craig Durland 88, 10/91 ==
  3. ========================================================================
  4.  
  5. Here is info on embedding the Mutt2 machine in a application and the
  6. Mutt2 machine itself.
  7.  
  8. The Mutt2 Machine is a virtual machine ment to be an embedded language.
  9. It is written in C for ease of porting.
  10.  
  11.  
  12.              Copyright 1991 Craig Durland
  13.     Distributed under the terms of the GNU General Public License.
  14.   Distributed "as is", without warranties of any kind, but comments,
  15.            suggestions and bug reports are welcome.
  16.  
  17. ========================================================================
  18. ==        Embedding the Mutt2 Machine                  ==
  19. ========================================================================
  20.  
  21. Data Types:
  22.   maddr
  23.   uint8
  24.  
  25. Example data structures:
  26.   block :
  27.     typedef struct
  28.     {
  29.       char  *name;        /* Name of the block (munged file name) */
  30.       uint8 *global_vars;    /* Where the global vars are in this block */
  31.       maddr code;        /* The start of the code in this block */
  32.       void *global_object_table;
  33.       int num_global_objects;
  34.     } CodeBlock;
  35.  
  36.   Programs:
  37.     typedef struct        /* program address table */
  38.     {
  39.       maddr addr;        /* address of routine */
  40.       short int block;    /* link to programs code block. 0 => dead */
  41.     } Pgm;
  42.   
  43. To embed the Mutt2 Machine in your C program, write the following
  44. routines:
  45.  
  46. Function:    FILE *MMopen_code_file(char *file_name)
  47. Description:
  48.   Open a Mutt code (.mco) file so that it can be loaded by the Mutt
  49.     Machine.
  50. Input:
  51.   name: Name of code file to open.  The extension is ".mco".  May have
  52.     a leading path.
  53. Returns:
  54.   FILE : Pointer to the opened code file.
  55.   NULL : Couldn't find the file.
  56. Notes:
  57.   You might want to parse a PATH environment variable.
  58.  
  59.  
  60. Function:    maddr MMpgm_addr(int pgm_id)
  61. Description:
  62.   Return the address of the Mutt routine that has pgm_id.  Also update 
  63.     MMglobal_vars, and MMglobal_object_table to point to the proper
  64.     areas.
  65. Input:
  66.   pgm_id : The id of a Mutt program.
  67. Returns:
  68.   Address of the start of the Mutt program code.
  69. Munges:
  70.   MMglobal_vars
  71.   MMglobal_object_table
  72. Notes:
  73.   You only need to update the globals if they will change.
  74.  
  75.   
  76. Function:    int MMpgm_lookup(char *pgm_name)
  77. Description:
  78.   Return the program id of the program that is named pgm_name.
  79. Input:
  80.   pgm_name: 
  81. Returns:
  82.   Program id.
  83. Notes:
  84.  
  85.  
  86. Function:    void MMblock_name(char *buf, *file_name)
  87. Description:
  88.   Create a block name (using file_name if you want) and put it into buf.
  89. Input:
  90.   buf:
  91.   file_name: 
  92. Munges:
  93.   buf
  94. Notes:
  95.  
  96.  
  97. Function:  int MMadd_block(
  98.         char *block_name;
  99.         maddr code;
  100.         uint8 *global_vars;
  101.         void *global_object_table;
  102.         int num_global_objects)
  103. Description:
  104.   Save some information that the Mutt Machine might need to use later.
  105. Input:
  106.   block_name:  A name returned by MMblock_name.  Useful to check to see
  107.     if a block is being reloaded.
  108.   code:  Pointer to the Mutt code.  MMpgm_addr() wants this.
  109.   global_vars:  Pointer to the block-global non-object variables.  Also
  110.     used by MMpgm_addr().
  111.   global_object_table:  Pointer to the block-global objects.  Used by
  112.     MMpgm_addr().
  113.   num_global_objects:  Number of block-global objects.  Used when
  114.     calling MMfree_block().
  115. Returns:
  116.   A block id that be used in MMadd_pgm().  You need block ids so you can
  117.     cross index the program table and the block table.  You save to save
  118.     memory by keeping a (program-name, block-id) tuple and using the
  119.     block table in MMpgm_addr().
  120. Notes:
  121.  
  122.  
  123. Function:  int MMadd_pgm(char *pgm_name; int block_id; maddr code_addr)
  124. Description:
  125.   Add a program to your program table.  This so MMpgm_addr() can get the
  126.     info.
  127. Input:
  128.   pgm_name:  Pointer the name of the program.  You only need to save a
  129.     copy of the pointer, the name itself is in the code block name table.
  130.   block_id:  Returned by MMadd_block.
  131.   code_addr: Start address of the code in the program.  Used by
  132.     MMpgm_addr().
  133. Returns:
  134.   TRUE:  Everything went as expected.
  135.   FALSE: Ran out of memory or some other real bad thing.
  136. Notes:
  137.  
  138.  
  139. Function:    void MMset_hooks()
  140. Description:
  141.   Hooks for Mutt programs.  When certain events occur in the
  142.     application, you might want to call a hook so your application can
  143.     be extended in useful ways.
  144. Notes:
  145.   Called from MM after every Mutt code block is loaded.
  146.   Call this at start up to make sure all hooks are
  147.     properly initialized to no hook.
  148.  
  149.   
  150. Function:    void MMbitch(char *message)
  151. Description:
  152.   A fatal error has occurred when running a Mutt program.  Inform the
  153.     user and bail out of the Mutt Machine (usually by calling
  154.     MMabort_pgm()).
  155. Input:
  156.   message:  Text that has some information about what happened.  You
  157.     might want to add some verbiage saying that the program is aborting.
  158. Notes:
  159.   Only the Mutt Machine aborts.  The application should be OK (it is up
  160.     to the application to decide).
  161.  
  162.  
  163. Function:    void MMmoan(char *message)
  164. Description:
  165.   Inform the user that the Mutt program has errored.
  166. Input:
  167.   message:  Text that has some information about what happened.
  168. Notes:
  169.   This is used for those times when MMabort_pgm() can't be called.
  170.   
  171.  
  172. Function:    void MMmsg(char *message)
  173. Description:
  174.   Give the user a message.  Used by MSG:  (msg "hoho") will result in
  175.     MMmsg("hoho");
  176. Input:
  177.   message:  Text for the user.
  178. Notes:
  179.  
  180.  
  181. Function:    void MMask(char *prompt, *buf)
  182. Description:
  183.   Ask the user for a response.  Used by ASK:  (ask "Press a key ") will
  184.     result in MMask("Press a key ", &buf);
  185. Input:
  186.   prompt:  
  187.   buf: where to put the reply.
  188. Munges:
  189.   buf
  190. Notes:
  191.  
  192.   
  193. Function:    int MMaux_fcn(char *aux_fcn_name)
  194. Description:
  195.   Run a aux function by name.  Aux functions are the functions that the
  196.     application defines and MM knows nothing about.  For example, say
  197.     the application is a spread sheet, you have C code that sums a
  198.     column and you want the Mutt name for this to be "sum-column".  Now,
  199.     when a Mutt program does a (sum-column n), MM looks around, can't
  200.     find a program named "sum-column", thinks it might be part of the
  201.     application and calls MMaux_fcn("sum-column").  Your C code can then
  202.     access the Mutt stack (see MMpull_nth_arg()) and sum that column.
  203. Input:
  204. Returns:
  205.   TRUE:  aux_fcn_name is real and I did it.
  206.   FALSE: aux_fcn_name is not something I know about.
  207. Notes:
  208.  
  209.  
  210. Function:    void MMxtoken(int token)
  211. Description:
  212.   Execute a token defined by the application.  If you compile a Mutt
  213.     program with a token file ("mc2 -t<token-file>"), MM will call
  214.     MMxtoken(token).  Using the MMaux_fcn() example, if you created a
  215.     token file with the entry "123 sum-column" in it, used that file to
  216.     compile a Mutt program with (sum-column 3) in it, then, when MM
  217.     executes that line, MMxtoken(123) will be called.  You then take 123
  218.     and figure out you need to call sum_column(3).
  219. Input:
  220.   token: 
  221. Notes:
  222.   MMxtoken() is short hand for MMaux_fcn().
  223.   Its assumed that token file is correct - you might want to do some
  224.     token checking if this is a bad assumption (it usually is).
  225.   Token files can really reduce the (static) space used by a Mutt
  226.     program and speed things up (because it gets rid of string lookups).
  227.   Token is usually an index into a array of function pointers or a case
  228.     in a switch statement.
  229.  
  230.  
  231. Function:    void MMgc_external_objects()
  232. Description:
  233.   Garbage collect all mortal (temporary) objects that may have been
  234.     created by Mutt programs and not freed by them.
  235.   This is typically called (by the Mutt Machine) after a pgm has been
  236.     run or aborted to clean up stuff the programmer forgot to or was
  237.     unable to (as in the case where the pgm was aborted).
  238. See also:  Section on garbage collection.
  239.  
  240.  
  241.  
  242.         Internal Routines of External Interest
  243.         -------- -------- -- -------- --------
  244.  
  245. Routines Mutt extension writers are interested in:
  246.  
  247. Function:    int MMpull_nth_arg(vsitem *val; int n)
  248. Description